home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
17 Bit Software 6: Level 6
/
17 Bit - Level 6 (1998)(Epic Marketing)[!].iso
/
quartz
/
q0364.dms
/
q0364.adf
/
PT-Fileformat.doc
< prev
next >
Wrap
Text File
|
1992-05-12
|
14KB
|
275 lines
Introduction.
=============
The text below was intended to be the documentation on the fileformat used
in this release of ProTracker. However, we decided to wait with the actual
implementation of the format until having released a couple of versions,
because we'd like to hear some comments, suggestions etc. upon it first.
So read it lightly, and feel free to post your opinion to one of the authors
(see the ReadMe.doc file elsewhere on the disk). Note that since this is only
a suggestion, don't start programming a revolutionary new piece of code based
on this info yet; we may change the format :)... Here we go...
- Signed Tom "Outland" Bech of CryptoBurners.
-**-
Protracker release 3.00 Beta. Fileformat documentation.
=======================================================
This document includes the complete documentation of the fileformat used in
Protracker 3.00, and instructions on how to use it. Fields marked "*Reserved*"
are reserved for future use and are guarantied to cause hangup if messed with.
General
-------
With this release of Protracker we have decided to change the filestructure
of the musicfiles produced with the program. We felt the old format was
too obsolete, messy and out of date for us to use any further. So we invented
this new format. The format is based upon Interchanged File Format (IFF)
chunks, originally developed by Electronic Arts, but now in widely use on the
Amiga. The format allows considerable flexibility and does not suffer too
severly from changes and updates, and is therefore perfect for our use.
The Format
----------
We will in this section introduce and describe each chunk type appearing in a
Protracker music file. Look in the next section for the sequencial description.
** Contents of Chunk "VERS":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "VERS" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 2 ???????? Version number (word).
10 6 "PT3.00" Version ID string.
--------------------------------------------------------------------------------
This chunk is used by Protracker to identify the producer of the module, and
if necessary perform upgrade-conversion if the file was made with a pre-
vious version of Protracker. There can be at maximum one "VERS" chunk in a
Protracker music file. This chunk is not critical; it may be obmitted, but
be aware of the possible incompatibility problems that may arise if it's left
out.
** Contents of Chunk "INFO":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "INFO" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 32 [..??..] Song name (string).
40 2 ???????? Number of instruments (word).
42 2 ???????? Number of positions (word).
44 2 ???????? Number of patterns (word).
46 2 ???????? Overall volume factor (word).
48 2 0006h Default speed (#VB) (word).
50 2 ???????? Packed field. See below.
--------------------------------------------------------------------------------
Protracker uses this chunk to set different internal variables, and to store
vital information used in replay and processing of the file. The song name
is a maximum 32 Chars long ASCII string. It need not be NULL-terminated.
Number of instruments indicates the number of instruments used in the song,
it may range from 0 to 65535. At present version number, however, there may
be maximum 255 instruments in one song. Number of positions reflects the
actual length of the song, that is; how many patterns that will be played during
a complete cycle. This number may vary from 0 to 65535. Number of patterns,
on the other side, reflects how many _different_ patterns that will be played
during the song. This number is used to calculate the total length (in bytes)
of the song. The Overall Volume factor is used to compute the final volume
of all channels after the individual channel-volumes have been figured out.
In this way it is easy to control the loudness of the music from the program/
song itself. Default speed is the number of VBlank frames between each pattern
position change, and is as default set to 0006h. The packed field consists
of these bits (right to left order):
Bit Meaning 0 1 Default
--------------------------------------------------------------------------------
0 Filter flag. Filter off. Filter on. 0
1 Timing method. VBlank. CIA timing (BPM). 0
2 File type. Module. Song (no instruments). 0
3 Packstatus. Packed patterns. Raw patterns. 1
4 Length flag. Equal pattern length. Variable pattern length. 0
5 Voices flag. 4 voices. 8 voices. 0
6 Sample res. 8 bit. 16 bit. 0
7 *Reserved* x
8 *Reserved* x
9 *Reserved* x
10 *Reserved* x
11 *Reserved* x
12 *Reserved* x
13 *Reserved* x
14 *Reserved* x
15 *Reserved* x
--------------------------------------------------------------------------------
There can be at most one "INFO" chunk in a Protracker musicfile. This chunk is
vital; it _must_ be present for the replay routine to function properly.
** Contents of Chunk "INST":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "INST" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 32 [..??..] Instrument name (string).
40 2 ???????? Length of instrument (word).
42 2 ???????? Instrument loop start (word).
44 2 ???????? Instrument loop length (word).
46 2 ???????? Instrument volume (word).
48 2 ???????? Instrument finetuning (integer).
--------------------------------------------------------------------------------
The "INST" chunk is used to store information about an instruments properties,
such as length and volume. The instrument name is a maximum 32 Chars long ASCII
string. It need not be NULL-terminated. The Length field describes the length
of the instrument (in words) and thus ranges from 0 to 128Kb (65535 words).
Instrument Loop Start sets the offset from which to start playing after the
first replay. This value may vary from 0 to the instrument length. Instrument
Loop End sets the length of the loop to play after the first replay, relative
to the loop start value. It may thus vary from 0 to [Ins_len-Loop_start].
Instrument volume indicates which volume to use in the replay of the sample,
if the song doesn't say differently. This value varies between 0 and 40h.
Instrument finetuning sets the sample-rate correction difference and varies
from -7 to 7 (0fff9 to 0007h).
There may be any number of "INST" chunks in a Protracker music file,
limited to the number of instruments actually used in the song. This
chunk is not vital; it may be left out if the song-only bit of the control
word in the "INFO" chunk is set. Otherwise, it should result in an error.
** Contents of Chunk "PPOS":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "PPOS" Chunk identifier.
4 4 0ffh Chunk length (in bytes).
8 256 [..??..] Pattern position table.
--------------------------------------------------------------------------------
This chunk contains the table defining which pattern to play in a given song-
position. Each entry in the table is a byte indicating which out of 256
possible patterns to play. There may be at maximum one "PPOS" chunk in a
Protracker musicfile. This chunk is vital; it _must_ be present to play the
song.
** Contents of Chunk "PTRN":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "PTRN" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 32 [..??..] Pattern name.
40 ? [..??..] Pattern data.
--------------------------------------------------------------------------------
This chunk is used in a module of variable pattern length. The chunk must thus
appear as many times as there are patterns in the song. The chunk length divided
by 8 ( >>3 ) will show the pattern length (default 64). Pattern name is a 32
byte long ASCII string, describing the pattern, eg. "Intro part 3". It need not
be NULL-terminated. This chunk is critical; it must be present in the file, or
it will be regarded invalid. NOTE: This chunk is not in use in the present
version (3.00B), and will be ignored if found.
** Contents of Chunk "SMPL":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "SMPL" Chunk identifier.
4 4 ???????? Chunk length (!in bytes!).
8 ? [..??..] Raw sample data.
--------------------------------------------------------------------------------
The "SMPL" chunk contains the raw sample data of an instrument. This chunk is
not critical; if the song-only bit of the "INFO" chunk is set, it may be
obmitted. If, however, the file is a module, then the number of "SMPL" chunks in
the file must be equal to or greater than the number of instruments used in the
song. If not, the file will be regarded incomplete.
** Contents of Chunk "CMNT":
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "CMNT" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 ? [..??..] Raw ASCII text.
--------------------------------------------------------------------------------
The "CMNT" chunk is used for a signature, comments, greetings, date of
completion or whatever information the composer wishes to include with his or
hers creation. This chunks is not critical; it may be left out and will
typically be ignored by most applications.
These are the chunks that may appear in a Protracker musicfile. If other chunks
are encountered, they will be ignored. Any program dealing with this fileformat
should perform tests to determine the validity of the file in consideration.
Using the Protracker.library will guarantee correct handling of musicfiles, and
we strongly encourage the use of this runtime shared library instead of hacking
away on your own. Look elsewhere on this disk for the library documentation,
the library can be found in the "LIBS/" directory.
The sequential format
---------------------
In this section we will describe how the various chunks are expected to be
located within the file. These rules _must_ be followed or it will wreak
havoc when tried manipulated with inside Protracker. Here comes the header in
table form:
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "FORM" Indicate start of IFF file.
4 4 ???????? File length.
8 4 "MODL" IFF type identifier.
-------------------------------------------------------------------------------
This header must be found in the start of the file, or it will be rejected as
not being a Protracker musicfile. From offset 12 in the file, things may vary
somewhat. The only rules are these: After a "INST" chunk a "SMPL" or a new
"INST" chunk _must_ follow. This "SMPL" chunk will be regarded as the sample
data of the instrument(s) preceding it. If after a "INST" chunk another "INST"
chunk follows, and the module-flag in the "INFO" chunk is set, then all "INST"
chunks following each other will share the same sampledata found in the first
"SMPL" chunk after them. Also, all "INST" and "SMPL" chunks must be found in
sequence. That is, when a "INST" chunk is found for the first time in a file,
all other "INST" and "SMPL" chunks must follow. If this is not so, an error
message should be given, and processing terminated. Note that in a song-only
file, no "SMPL" chunks should be included. If any "SMPL" chunks are encountered
in such a file, they should be ignored and a warning given. All other chunks
used in a musicfile may be located anywhere in the file, usually in the
beginning of it, but no assumptions of their locations should be taken. Note
that all used chunks _must_ be found _before_ the "BODY" chunk, which is the
last chunk to be found in the file. Searching for chunks should stop when
encountering a "BODY" chunk. The "BODY" chunk is constructed like this:
OFFSET Length Contents Meaning
--------------------------------------------------------------------------------
0 4 "BODY" Chunk identifier.
4 4 ???????? Chunk length (in bytes).
8 ? [..??..] Raw pattern data.
-------------------------------------------------------------------------------
Chunk summary
-------------
Now follows a list of the chunks that have meaning in a Protracker musicfile:
Chunk Function Critical?
-------------------------------------------------------------------------------
"VERS" Contains information about the producer of the file. No
"INFO" Contains vital information and standard settings. Yes
"INST" Information about instruments; such as length, volume etc. Yes
"SMPL" Raw sample data associated with one or more instruments. No
"PPOS" Position table. Information about patternsequence. Yes
"CMNT" Comments, greetings etc. Contains information in ASCII code. No
"PTRN" Pattern data. Used only in modules of varying patternlengths. Yes
"BODY" Pattern data. Used in modules of equal patternlengths (default). Yes
-------------------------------------------------------------------------------
/* End Of File */